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Foreword 



id , 



This Technical Specification has been produced by the 3 Generation Partnership Project (3GPP). 

3GPP acknowledges the contribution of the Parlay X Web Services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

x the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



rd , 



The present document is part 5 of a multi-part deliverable covering the 3 Generation Partnership Project; Technical 

Specification Group Core Network; Open Service Access (OSA); Parlay X Web Services, as identified below: 

Part 1: "Overview and common data definitions"; 

Part 2: "Third party call"; 

Part 3: "Call Notification"; 

Part 4: "Short Messaging"; 

Part 5: "Multimedia Messaging"; 

Part 6: "Payment"; 

Part 7: "Account management"; 

Part 8: "Terminal Status"; 

Part 9: "Terminal location"; 

Part 10: "Call handling"; 

Part 11: "Audio call"; 

Part 12: "Multimedia conference"; 

Part 13: "Address list management"; 

Part 14: "Presence". 
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1 Scope 

The present document is Part 5 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Multimedia Messaging Web Service aspects of the interface. All aspects of the 
Multimedia Messaging Web Service are defined here, these being: 

• Name spaces. 

• Sequence diagrams. 

• Data definitions. 

• Interface specification plus detailed method descriptions. 

• Fault definitions. 

• Service policies. 

• WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CN WG5, ETSI TISPAN and The Parlay Group. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common". 

[7] W3C Note (11 December 2001): "SOAP Messages with Attachments". 

NOTE: Available at http://www.w3.org/TR/SOAP-attachments . 

[8] 3GPP TS 23.140 "Multimedia Messaging Service (MMS); Functional description; Stage 2". 

[9] RFC2822: "Internet Message Format". 
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NOTE: Available at http://www.ietf.org/rfc/rfc2822.txt 

3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 
Additionlly the following definition is needed: 

Shortcode: a short telephone number usually 4 to 6 digits long, this is represented by the 'tel:' URI defined in [6]. 
Whitespace: see definition for CFWS as defined in RFC2822 [9]. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] and the following apply: 

EMS Enhanced Messaging Service 

IM Instant Messaging 

MMS Multimedia Messaging Service 

MMS-C Multimedia Messaging Service - Centre 

SMS Short Message Service 



Detailed service description 



Currently, in order to programmatically receive and send Multimedia Messages, it is necessary to write applications 
using specific protocols to access MMS functions provided by network elements (e.g. MMS-C). This approach requires 
application developers to have a high degree of network expertise. 

This contribution defines a Multimedia Messaging Web Service that can map to SMS, EMS, MMS, IM, E-mail, etc. 

The choice is between defining one set of interfaces per messaging network or a single set common to all networks; 
e.g. we could define sendMMS, sendEMS, sendSMS, etc., or just use sendMessage. Although the more specific the API 
the easier it is to use, there are advantages to a single set of network-neutral APIs. These advantages include: 

• improved service portability; 

• lower complexity, by providing support for generic user terminal capabilities only. 

For this version of the Parlay X specification, we provide sets of interfaces for two messaging Web Services: Short 
Messaging (part 7) and Multimedia Messaging (this part), which provides generic messaging features (including SMS). 

Multimedia Messaging provides operations (see clause 8.1, SendMessage API) for sending a Multimedia message to the 
network and a polling mechanism for monitoring the delivery status of a sent Multimedia message. It is expected that a 
future release of this specification will also provide an asynchronous notification mechanism for delivery status. 

Multimedia Messaging also allows an application to receive Multimedia messages. Both a polling (see clause 8.2, 
ReceiveMessage API) and an asynchronous notification mechanism (see clause 8.3, Message Notification API) are 
available. 

Figure 1 shows an example scenario using sendMessage and getMessageDeliveryStatus to send data to subscribers and 
to determine if the data has been received by the subscriber. The application invokes a Web Service to retrieve a stock 
quote (1) and (2) and sends the current quote - sendMessage - using the Parlay X Interface (3) of the Multimedia 
Messaging Web Service. After invocation, the Multimedia Message Web Service sends the message to an MMS-C 
using the MM7 interface (4) for onward transmission (5) to the subscriber over the Mobile network. 

Later, when the next quote is ready, the application checks to see - getMessageDeliveryStatus - if the previous quote has 
been successfully delivered to the subscriber. If not, it may for instance perform an action (not shown) to provide a 
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credit for the previous message transmission. This way, the subscriber is only charged for a stock quote if it is delivered 
on time. 




Multimedia 
Message Web 
Service 



User 
profile 



I Parlay XI/F 



1 i 



contentl =get Stocky Jote {) 



Retrieve 
user Profile 



k<_ ioi 



messageld= sendMessage( content ) 

status= getMessageDeliveryStatus (messageld) 
if status=Message_Waiting 



content2 =getStockQuote () 
messageld= sendMessage ( content2 ) 




Figure 1 : Multimedia Messaging Scenario 



Namespaces 



The SendMessage interface uses the namespace: 

www.csapi.org/wsdl/parlayx/multimedia messaging/send/v2 
The ReceiveMessage interface uses the namespace: 

www.csapi.org/wsdl/parlayx/multimedia messaging/receive/v2 
The MessageNotification interface uses the namespace: 

www.csapi.org/wsdl/parlayx/multimedia messaging/notification/v2 
The data types are defined in the namespace: 

www.csapi.org/schema/parlayx/multimedia messaging/v2 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in 
XML Schema [5], The use of the name 'xsd' is not semantically significant. 



Sequence diagrams 



6.1 Send picture 



With the advent of picture capable phones, the exchange of photos to mobile phones is becoming more common place. 
This sequence diagram shows an application where a person can send a picture from an online photo album to a mobile 
phone. 
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XML schema data type definition 



7.1 DeliveryStatus enumeration 



List of delivery status values. 



Enumeration 


Description 


Delivered 


Successful delivery. 


DeliveryUncertain 


Delivery status unknown: e.g. because it was handed off to another network. 


Deliverylmpossible 


Unsuccessful delivery; the message could not be delivered before it expired. 


MessageWaiting 


The message is still queued for delivery. This is a temporary state, pending transition to one of the 
preceding states. 
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7.2 



MessagePriority enumeration 



List of delivery priority values. 



Enumeration 


Description 


Default 


Default message priority 


Low 


Low message priority 


Normal 


Normal message priority 


High 


High message priority 



7.3 Deliverylnformation structure 



Delivery status information. 



Element name 


Element type 


Description 


address 


xsd:anyURI 


Address associated with the delivery status. The address field is coded as a URI. 


deliveryStatus 


DeliveryStatus 


Parameter indicating the delivery status. 



7.4 Message Reference structure 

Message information. 



Element name 


Element type 


Description 


messageldentifier 


xsd:string 


OPTIONAL: If present, contains a reference to a message stored in the Parlay X 
gateway. If the message is pure text, this parameter is not present. 


messageService 
ActivationNumber 


xsd:string 


Number associated with the invoked Message service, i.e. the destination address 
used by the terminal to send the message. 


senderAddress 


xsd:anyURI 


Indicates message sender address. 


subject 


xsd:string 


OPTIONAL: If present, indicates the subject of the received message. This 
parameter will not be used for SMS services. 


priority 


MessagePriority 


The priority of the message: default is Normal. 


message 


xsd:string 


OPTIONAL: If present, then the messageldentifier is not present and this 
parameter contains the whole message. The type of the message is always pure 
ASCII text in this case. The message will not be stored in the Parlay X gateway. 



7.5 MessageURI structure 



Message location information. 



Element 
name 


Element type 


Description 


bodyText 


xsd:string 


Contains the message body if it is encoded as ASCII text. 


fileReferences 


xsd:anyURI 
[0.. unbounded] 


This is an array of URI references to all the attachments in the Multimedia 
message. These are URIs to different files, e.g. GIF pictures or pure text files. 
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Web Service interface definition 



8.1 Interface: SendMessage 

Operations to send messages and check status on sent messages. 
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8.1.1 Operation: SendMessage 

Request to send a Message to a set of destination addresses, returning a requestldentifier to identify the message. The 
requestldentifier can subsequently be used by the application to poll for the message status, i.e. using 
getMessageDeliveryStatus to see if the message has been delivered or not. The content is sent as a Attachment as 
specified in SOAP Messages with Attachments [7]. 

Addresses may include group URIs as defined in the Address List Management specification. If groups are not 
supported, a PolicyException (POL0006) will be returned to the application. 



8.1.1.1 



Input message: SendMessageRequest 



Part name 


Part type 


Description 


Addresses 


xsd:anyURI [0.. unbounded] 


Destination addresses for the Message. 


SenderAddress 


xsd:string 


Message sender address. This parameter is not allowed for all 3 ra party 
providers. Parlay X server needs to handle this according to a SLA for 
the specific application and its use can therefore result in a 
PolicyException. (optional) 


Subject 


xsd:string 


Message subject. If mapped to SMS this parameter will be used as the 
senderAddress, even if a separate senderAddress is provided, 
(optional) 


Priority 


MessagePriority 


Priority of the message. If not present, the network will assign a priority 
based on an operator policy, (optional) 


Charging 


Common :Charginglnformation 


Charging to apply to this message, (optional) 



NOTE: The input message may also contain attachments, with appropriate content as defined by SOAP Messages 
with Attachments [7]. 



8.1.1.2 



Output message: SendMessageResponse 



Part name 


Part type 


Description 


Requestldentifier 


xsd:string 


It is a correlation identifier that is used in a getMessageDeliveryStatus message 
invocation, i.e. to poll for the delivery status of all of the sent Messages. 



8.1 .1 .3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 

• SVC0004 - No valid addresses. 

• SVC0006 - Invalid group. 
PolicyException from [6]: 

• POL0001 - Policy error. 

• POL0006 - Groups not allowed. 

• POL0007 - Nested groups not allowed. 

• POL0008 - Charging not supported. 

8.1.2 Operation: GetMessageDeliveryStatus 

This is a poll method used by the application to retrieve delivery status for each message sent as a result of a previous 
sendMessage message invocation. The requestldentifier parameter identifies this previous message invocation. 
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8.1.2.1 



Input message: GetMessageDeliveryStatusRequest 



Part name 


Part type 


Description 


Requestldentifier 


xsd:string 


Identifier related to the delivery status request. 



8.1.2.2 



Output message: GetMessageDeliveryStatusResponse 



Part name 


Part type 


Description 


DeliveryStatus 


Deliverylnformation 
[0.. unbounded] 


It is an array of status of the messages that were previously sent. Each array 
element represents a sent message: i.e. its destination address and its delivery 
status. 



8.1 .2.3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.2 Interface: ReceiveMessage 

Operations to retrieve messages that have been received. 

8.2.1 Operation: GetReceivedMessages 

This method enables the application to poll for new messages associated with a specific registrationldentifier. If the 
registrationldentifier is not specified, the Parlay X server will return references to all messages sent to the application. 
The process of binding different registrationldentifier parameters to applications is an off-line process. The Parlay X 
gateway shall not allow an application to poll for messages using registrationldentifier parameters that are not 
associated with the application. The priority parameter may be used by the application to retrieve references to higher 
priority messages, e.g. if Normal is chosen only references to high priority and normal priority messages are returned. If 
the priority parameter is omitted all message references are returned. 



8.2.1.1 



Input message: GetReceivedMessagesRequest 



Part name 


Part type 


Description 


Registrationldentifier 


xsd:string 


Identifies the off-line provisioning step that enables the application to receive 
notification of Message reception according to specified criteria. 


Priority 


MessagePriority 


OPTIONAL. The priority of the messages to poll from the Parlay X gateway. All 
messages of the specified priority and higher will be retrieved. If not specified, all 
messages shall be returned, i.e. the same as specifying Low. 



8.2.1.2 



Output message: GetReceivedMessagesResponse 



Part name 


Part type 


Description 


Messages 


MessageReference 
[0.. unbounded] 


It contains an array of messages received according to the specified filter of 
registrationldentifier and priority. 



8.2.1.3 Referenced faults 

ServiceException from [6]: 
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• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.2.2 Operation: GetMessageURIs 

This method will read the different parts of the message, create local files in the Parlay Gateway and return UPJ 
references to them. The application can then simply read each file or just have them presented as links to the end-user. 
The URIs to the files will be active for an agreed time. 

8.2.2.1 Input message: GetMessageURIsRequest 



Part name 


Part type 


Description 


MessageRef Identifier 


xsd:string 


The identity of the message to retrieve. 



8.2.2.2 Output message: GetMessageURIsResponse 



Part name 


Part type 


Description 


Message 


MessageURI 


It contains the complete message, i.e. the textual part of the message, if such exists, and a 
list of file references for the message attachments, if any. 



8.2.2.3 Referenced faults 

ServiceException from [6]: 

• SVC0001 - Service error. 

• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.2.3 Operation: GetMessage 

This method will read the whole message. The data is returned as an attachment, as defined in SOAP Messages with 
Attachments [7], in the return message. 

8.2.3.1 Input message: GetMessageRequest 



Part name 


Part type 


Description 


MessageRef Identifier 


String 


The identity of the message 



8.2.3.2 Output message: GetMessageResponse 



Part name 


Part type 


Description 


None 







8.2.3.3 Referenced faults 

ServiceException from [6]: 
• SVC0001 - Service error. 
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• SVC0002 - Invalid input value. 
PolicyException from [6]: 

• POL0001 - Policy error. 

8.3 Interface: MessageNotification 

MessageNotification is the application side notification interface to which multimedia messages are delivered. 

8.3.1 Operation: NotifyMessage Reception 

The notification is used to send a multimedia message to the application. The notification will occur only if the 
multimedia message fulfils the criteria specified when starting the multimedia message notification. 



8.3.1.1 



Input message: NotifyMessageReception Request 



Part name 


Part type 


Description 


correlator 


xsd:string 


Correlator provided in request to set up this notification 


Message 


MessageReference 


This parameter contains all the information associated with the received message. 



8.3.1.2 



Output message: NotifyMessageReception Response 



Part name 


Part type 


Description 


None 







8.3.1.3 

None. 



Referenced faults 



8.4 Interface: MessageNotificationManager 

The multimedia message notification manager enables applications to set up and tear down notifications for multimedia 
messages online. The means to provision notifications offline are not specified here. 

8.4.1 Operation: StartMessageNotification 

Start notifications to the application for a given Message Service activation number and criteria. 

The Message Service activation number is an Address Data item as defined in 3GPP TS 29.199-1 [6]. A Shortcode is an 
example of an Address Data item. 

The correlator provided in the reference must be unique for the application Web Service at the time the notification is 
initiated, otherwise a ServiceException (SVC0005) will be returned to the application.. 

If specified, criteria will be used to filter messages that are to be delivered to an application. If criteria are not provided, 
or is an empty string, then all messages for the MessageServiceActivationNumber will be delivered to the application. 
The MessageServiceActivationNumber and criteria combination must be unique. If a criteria overlaps then SVC0008 
will be returned to the application and the notification will not be set up. Note that the use of criteria will allow different 
notification endpoints to receive notifications for the same MessageServiceActivationNumber. The combination of 
MessageServiceActivationNumber and criteria must be unique, so that a notification will be delivered to only one 
notification endpoint. If no match is found, the message will not be delivered to the application. 
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8.4.1.1 



Input message: StartMessageNotification Request 



Part name 


Part type 


Description 


Reference 


common:SimpleReference 


Notification endpoint definition 


MessageServiceActivationNumber 


xsd:anyURI 


the destination address of the multimedia message 


Criteria 


xsd:string 


Optional. 

The text to match against to determine the application 

to receive the notification. 

This text is matched agains the first word, as defined 

as the initial characters after discarding any leading 

Whitespace and ending with a Whitespace or end of 

the string. The matching shall be case-insensitive. 

If the subject of the multimedia message is present it 

shall be used as the string, if not the string is defined 

as the first plain/text part of the content (see 3GPP TS 

23.140 [8]). 



8.4.1.2 



Output message: StartMessageNotification Response 



Part Name 


Part Type 


Description 


none 







8.4.1.3 Referenced Faults 

ServiceException from [6] 

• SVC0001 - Service error 

• SVC0002 - Invalid input value 

• SVC0005 - Duplicate correlator 

• SVC0008- Overlapping Criteria 
PolicyException from [6] 

• POL000 1 - Policy error 

8.4.2 Operation: StopMessageNotification 

The application may end a multimedia message notification using this operation 



8.4.2.1 



Input message: StopMessageNotificationRequest 



Part name 


Part type 


Description 


Correlator 


xsd:string 


Correlator of request to end 



8.4.2.2 



Output message: StopMessageNotification Response 



Part Name 



Part Type 



Description 



None 



8.4.2.3 Referenced Faults 

ServiceException from [6] 

• SVC0001 - Service error 

• SVC0002 - Invalid input value 
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• POL000 1 - Policy error 
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9 Fault definitions 

9.1 ServiceException 
9.1.1 Void 

The fault code (SVC0230) is reserved and shall not be used. 



10 Service policies 



Service policies for this service 



Name 


Type 


Description 


GroupSupport 


xsd:Boolean 


Groups may be included with addresses 


NestedGroupSupport 


xsd:Boolean 


Are nested groups supported in group definitions 


ChargingSupported 


xsd:Boolean 


Charging supported for send message operation 
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Annex A (normative): 

WSDL for Multimedia Messaging 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-05-620-doclit.zip) which accompanies the present document. 
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Annex B (informative); 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Dec 2003 


CN 21 


NP-030552 


-- 


-- 


Submitted to CN#22 for Information 


1.0.0 




Jan 2004 










Added The W3C WSDL representation of the APIs specified in the 
present document is contained in a set of files which accompany the 
present document: 

px0326rpcenc.zip 

px0326rpclit.zip 


1.0.1 




Jun 2004 


CN_24 


NP-040274 


— 


— 


Split into multi-part specification. 29.199-0n, for n=1,2...9. 
Submitted to CN#24 for Information 


1.0.3 




Sep 2004 


CN 25 


NP-040360 


-- 


-- 


Draft v200 submitted to TSG CN#25 for Approval. 


2.0.0 


6.0.0 


Dec 2004 


CN_26 


NP-040487 


001 


— 


Add MessageNotificationManager interface to PXWS Multimedia- 
Messaging 


6.0.0 


6.1.0 


Mar 2005 


CN 27 


NP-050021 


002 


-- 


Correct criteria 


6.1.0 


6.2.0 


Mar 2005 


CN 27 


NP-050021 


003 


-- 


Fix StopMessageNotification message part 


6.1.0 


6.2.0 
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History 



Document history 


V6.1.0 


December 2004 


Publication 


V6.2.0 


March 2005 


Publication 
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